Lua scripts

We use a scripting language called Lua, which has been extended to provide functionality specific to the Pharos Controllers. Tutorials and reference manuals for the Lua language can be found at www.lua.org. We will not attempt to document the Lua language here, but just the Pharos specific extensions. Please contact support if you need assistance with preparing a script or if you would like some examples as a starting point.

Lua script editor

The Lua Script Editor allows you to edit scripts from Triggers Conditions and Actions, and Custom presets within Designer. The Script Editor is launched by pressing the Launch Editor button in the trigger properties:

The main area of the editor is the code editor where you enter the source code of the script. The code editor will colour the Lua syntax to aid readability. Standard clipboards shortcuts and undo/redo are supported.

To import a Lua script from an external file, use File > Import (Ctrl+I).

To save a Lua script to a file, use File > Export (Ctrl+E).

To compile the script and check for syntax errors, use Build > Build (F7). If there are errors in the script, they will be displayed at the bottom of the window.

When you have finished editing the script, press Ok to close the Script Editor. If there are still errors in your script, you will be prompted whether the invalid source should be saved or not.

To discard any changes close the Script Editor and select Discard from the confirmation dialog.

Debugging Lua scripts

If your script contains no errors, use Debug > Run (F5) to execute it in a debugger. This will run the script and report any runtime errors in the Output tab below the source editor. Note that only Custom preset scripts can be executed in the debugger.

If there are errors, you can place breakpoints in the source to force the debugger to halt execution at that point and allow you to examine the state of variables and execute further instructions one at a time.

To add/remove a breakpoint on a line of source code, click the mouse to the left of the relevant line number, or use Debug > Toggle Breakpoint (F9) to set a breakpoint at the text cursor. Now, when you run the script with Debug > Run (F5), the debugger will halt at the first breakpoint that it encounters.

When the debugger is halted, you can examine the values of variable in the script in the Watch tab below the source editor.

• To execute the next line of code, use Debug > Step Over (F10).
• If the debugger is halted at a function call, use Debug > Step Into (F11) to step into the function.
• To step out of the current function, use Debug > Step Out (Shift+F11).
• To resume normal execution, use Debug > Run (F5).
• To terminate execution immediately and return to editing the source, use Debug > Stop (Ctrl+F5).
• While a script is executing, use Debug > Break to halt execution at the current line.

Pharos language extensions for triggers

Accessing the realtime clock (local to this Controller)

NOTE: The location of the Controller must be set correctly in project properties for these to return the correct values.

Accessing the calculated sunrise and sunset times (local to this Controller)

NOTE: The location of the Controller must be set correctly in project properties for these to return the correct values.

Accessing the calculated twilight times (local to this Controller)

NOTE: The location of the Controller must be set correctly in project properties for these to return the correct values.

TPC user interface control

These are only executed on the local Controller, which must be a TPC.

Accessing the current state of the digital inputs on this Controller

Accessing the values of DMX inputs on the local Controller

Checking the local Controller number

Checking the status of timelines (local to this Controller)

Injecting a trigger

Equivalent to clicking a trigger in the web control screen.

Timeline control

Note that unlike a normal trigger action these will only affect the local Controller. This can be a powerful additional feature in certain situations. If you want to fire a timeline system-wide then inject an appropriate trigger.

Timecode control (local to this Controller)

Fixture control (local to this Controller)

A script can directly control fixtures as if it was a high priority timeline. It can only control fixtures local to the Controller on which the script is running. It can also only control whole fixtures – there is no access to individual elements of compound fixtures.

Accessing the values of DMX channels (local to this Controller)

Park and Unpark DMX channels (local to this Controller)

The value for the universe argument for both of the above functions depends on the protocol type:

For example:

Accessing the current state of the digital inputs on a RIO

For example:

myRIO = get_rio(RIO_80, 2)
rioInput1 = myRIO[1]

Accessing the current state of BPS buttons and setting BPS LEDs

For example:

myBPS = get_bps(1)
if (myBPS:get_state(2) == HELD) then
    mpBPS:set_LED(2, FAST_FLASH, 255, 0.5)
end

Accessing trigger variables

The variable must have been captured by the trigger running the script.

Writing messages to the Controller's status log

Storing data on the memory card

Using a Lua script it is possible to store data as a file on the memory card. Unlike variables in memory, data stored to a file will not be affected by resetting the Controller or cycling the power. The file can be read back at any time to access the data. This can be very useful in show control situations where some system status information needs to be stored persistently even if the Controller is reset. Alternatively it can allow you to store large data tables on the memory card and only read the data when it is needed.

To work with files on the memory card use the standard I/O library functions described in the Lua documentation. When writing to a file always close the file explicitly to make sure your data is correctly stored. The full file path to a file on the memory card differs per Controller, so we have provided a function to create the full file path for you:

For example:

file = io.open(get_resource_path("myfile"), "r")
if (file ~= nil) then
    local line = file:read()
    file:close()
end

Related Topics